Documentation for Translator.pkg
Version 1.1
Date: 9/5/00
Author: Jonathan Kipling Knight, Prism Research


This Newton package designed for Newton 2.x devices, extends the global
function Translator(obj,xltr,store,progressFn).  This function is used
for the most part for transporting NewtonScript objects between Newtons.
The original function provided by the Newton 2.x Operating System has
two translators: xltr := 'flattener; and xltr := 'unflattener.  Use of
these will convert a frame object to and from a Newton Streamed Object
Format (NSOF) binary.  The new ability provides the translation of any
NewtonScript object, not just frames.  In addition, it makes a more
compact binary when sub-objects are duplicates.

Translator() now has even more translators than NSOF conversion.
The new translators are:

ClassOf(obj)	xltr		description
'bits		'picture	Newton Bitmap to Newton Picture
'mask		'picture	Newton Bitmap mask to Newton Picture
'bits		'PICT	Newton Bitmap to PICT file
'mask		'PICT	Newton Bitmap mask to PICT file
'bits		'picture	Newton Bitmap to Mac icon resource
'mask		'picture	Newton Bitmap mask to icon resource
'picture		'bitmap	Newton Picture to Newton Bitmap
'picture		'mask	Newton Picture to Newton Bitmap mask
'picture		'PICT	Newton Picture to PICT file
'PICT		'picture	PICT file to Newton Picture
'string		'ASCII	Unicode string to ASCII string
'ASCII		'string	ASCII string to Unicode string
sound		'AIFF	Newton sound to AIFF file
sound		'AIFC	Newton sound to AIFF-C file
sound		'GSM		Newton sound (gsm) to .AU.GSM file
sound		'AU		Newton sound (u-law) to AU file
sound		'WAV		Newton sound (uncomp) to WAVE file
'AIFF		'sound	AIFF file to Newton sound
'AIFC		'sound	AIFF-C file to Newton sound
'GSM			'sound	.AU.GSM file to Newton sound
'AU			'sound	AU file to Newton sound
'WAV			'sound	WAVE file to Newton sound

This extension is made available to anybody for programming purposes.
It will not interfere with existing use of the global function "Translator".
There is a way to add more translators that can be accessed with a call to
Translator().  The new functions RegTranslator(class,xltr,fn) and
UnRegTranslator(class,xltr) were added to insert new translators into the
system.  The variable class is the class symbol of the object to be
translated as returned by ClassOf(obj).  The variable xltr is the symbol
that uniquely identifies the translator.  The variable fn is the function
taking the same arguments as the original Translator global function.  For
example, a program would register the translator with a call

	myTranslator := func( object, store, progressFunction )
	begin
		// do my work on object here
	end;
	RegTranslator( myClassSymbol, myTransSymbol, myTranslator );
	
Then to unregister the translator call

	UnRegTranslator( myClassSymbol, myTransSymbol )
	
A user of the translator would call

	SetClass(myObject, myClassSymbol);
	myStore := GetDefaultStore(); // or whereever (could be nil)
	myProgressFn := func( bytesSoFar, bytesMax )
	begin
		// Display progress
	end;
	Translator( myObject, myTransSymbol, myStore, myProgressFn )

For questions regarding the use or programming new translators please don't
hesitate to contact Kip Knight at Prism Research.
http://hometown.aol.com/NewtsPrism
NewtsPrism@aol.com


Fix history:
Version 1.1 5 September 2000
	Fixed sampling rate error in converting AU mu-Law sounds.
	Added more capabilities for larger files.
Version 1.0	19 July 2000
	Initial release
